═══ 1. Licensing agreement ═══ The term LICENSE is used to refer to the ASCII file containing a copy of this license. The term PACKAGE here is used to refer to the header files, the libraries, the documentation, and LICENSE. The term AUTHOR is used to refer to the developer of PACKAGE. PACKAGE is copyrighted (c) 1993, 1994 by its AUTHOR, Lawrence W. Salomon, Jr. and is the sole property of AUTHOR. You are hereby granted a license to use PACKAGE in your applications and freely distribute PACKAGE if and only if the following condition(s) are met: o All files in PACKAGE are included in the distributed files and remain in their original form. o If the contents of the PACKAGE are distributed using any of the file compression programs available (PKZIP, ZIP, ZOO, etc.), LICENSE must not be included in the compressed file but instead must remain separate. o None of the components or any part of any component of PACKAGE may be used or included in a commercial product without the expressed, written consent of AUTHOR. A commercial product is defined to be a group of one or more applications which are packaged together and sold for profit. By using any component or any part of any component of PACKAGE, you are indicating that you agree to and are thereby bound to the terms of this license. ═══ 2. Introduction ═══ Do you ever find yourself writing a new program and wishing that you already had a routine to parse the command line? Or how about a routine that performs signal processing? Or maybe a set of linked list functions? Often times, I have often been in this very situation, writing new code then discovering that I have need of routines that should be fairly common. Instead of simply writing the routines for each application that required them, I started maintaining my own software library of commonly used routines, which you have here. These routines provide easy access to a host of functions that you used to have to write yourself. The functions are separated into groups, listed below: o Common routines o Buffer routines o Communication routines o Debugging routines o File routines o Link-list routines o Memory allocation routines o Object handling routines o Set routines o Signal routines o Sprite routines o String routines o Screen I/O routines o Windowing routines Additionally, the following topics are also available: o Licensing agreement o Using Common/2 in your applications o About errors, bugs, and suggestions o What's New in this Release A couple of notes are needed: o As you use Common/2, you may notice that the library seems to have been built out of "spare parts", because there is lacking a tight level of integration. This is true, and I hope to resolve this in the near future by taking such steps as having each function return an error code (like the kernel APIs), and combining the error codes (instead of having a group for the memory routines, another group for the object routines, etc.). If you have any suggestions on how the library can be made to fit together better, I would be most interested in hearing them. ═══ 2.1. Using Common/2 in your applications ═══ Common/2 was compiled using IBM's C-Set++ compiler; compatibility with other 32-bit compilers has not been tested. It does require you to have the Programmer's Toolkit installed on your machine or its functional equivalent, however. You should place the files common.h and cmndefs.h in a directory specified by the INCLUDE environment variable. Additionally, you should place the .LIB files in a directory specified by the LIB environment variable and the .DLL files in a directory specified by the LIBPATH environment variable. Note that must be included before including . Do not explicitly include because it is included by . As with , before including you should define the appropriate constants to indicate which portions of the library you would like to use: INCL_CMNBUF Buffer routines (CmnBuf) INCL_CMNCOM Communication routines (CmnCom) INCL_CMNDBG Debugging routines (CmnDbg) INCL_CMNFIL File routines (CmnFil) INCL_CMNLST Linked list routines (CmnLst) INCL_CMNMEM Memory routines (CmnMem) INCL_CMNOBJ Object routines (CmnObj) INCL_CMNSET Set routines (CmnSet) INCL_CMNSIG Signal routines (CmnSig) INCL_CMNSPR Sprite routines (CmnSpr) INCL_CMNSTR String routines (CmnStr) INCL_CMNVIO VIO routines (CmnVio) INCL_CMNWIN Window routines (CmnWin) INCL_COMMONALL All sections The general purpose routines (those that begin with Cmn only) are always included regardless of the constants defined. ═══ 2.2. About errors, bugs, and suggestions ═══ Often, when something doesn't quite work correctly, it is because the wrong handle was passed to the function which returned the unexpected result. Before crying "wolf", you should first call CmnQueryHandle to insure that you are giving the function what it expects. If that still doesn't help, if you have some suggestions, if you have a set of routines that you would like to donate to the library, or if you would like to translate the programming reference and header files into other languages, feel free to send me mail via the Internet. My address is "os2man@panix.com". If you are describing what you think is a bug, please describe the steps needed to recreate the problem and include code when possible. ═══ 2.3. What's New in this Release ═══ Changes resulting in release 1.5.0 include: o The CmnBuf routines were added. o The functions CmnFilCopyDiskette() and CmnFilFormatDiskette() were added. Changes resulting in release 1.4.0 include: o The library was moved from a .LIB to a .DLL in hopes of someday writing Rexx interfaces for some or all of the routines. This impacted a number of things: - The CmnVio routines, since CmnVioLoadMessage() assumes that messages will be bound (with MSGBIND) to the DLL and not the EXE file; if an EXE uses MSGBIND to bind its messages to itself, CmnVioLoadMessage() (and thus CmnVioDisplayMessage(), since it is dependent on the former) would return an error. - If you write an application that uses non of the PM-dependent routines (CmnSpr and CmnWin), and tried to run the application in a non-PM environment (e.g. booting from the installation diskettes), OS/2 would return an error since, by virtue of the fact that your application is linked to the DLL, PM is required. To alleviate this problem, the DLLs have multiplied from two to four, and a naming convention was established to allow for this. The format of the DLL and LIB file names is CMN32te. "t" is the "threaded" option and can be S for single-threaded or M for multi-threaded. "e" is the "environment" option and can be V for routines that do not require PM (VIO), or P for routines that do require PM. o 16-bit support was removed. This was due to the fact that we're in the second release of a 32-bit OS/2, so 16-bit seemed rather redundant. The code for all existing functions is still there, but no new development will make provisions for 16-bit compatibility, nor will the 16-bit version of the library be released in this package. Should you need this, contact me via email. o The constant INCL_CMNLIB was renamed to INCL_COMMONALL, in the (admittedly unlikely) event that a CmnLib subsystem is added. o The constant SPL_ERROR was renamed to SPL_ERR_ERROR to avoid conflicts with the constant of the same name in . o Minor bugs with the CmnCom subsystem were fixed. o A minor bug with the CmnFilSearchFiles() function was fixed. o A minor bug with the CmnMemFreeMem() was fixed. o The CmnFilSplitFilename() function was added. o The CmnWinSavePosToBuffer() and CmnWinRestorePosFromBuffer() functions were added and the CmnWinSavePosition() and CmnWinRestorePosition() functions were modified to utilize these new functions. o The functions CmnStrPadString() and CmnStrStripSpace() were added. o The function CmnVioGetString() has been added. o The sprite subsystem (INCL_CMNSPR) was added. o All function pointer typedefs were modified to include the EXPENTRY attribute to allow for non-IBM compilers. ═══ 3. Common routines ═══ The purpose of this group is to provide functions which apply to all of the function groups. Listed below are the functions which comprise this group: o CmnQueryHandle o CmnQueryHandleInfo o CmnQueryVersion o CmnSetHandleInfo ═══ 3.1. CmnQueryHandle ═══ CmnQueryHandle Purpose This function returns the type of the specified handle. Syntax (USHORT)CmnQueryHandle(lhHandle); Parameters lhHandle (LHANDLE) - specifies the handle to query. Returns This function returns one of the following values: QH_ERROR QH_HCCCONNECT QH_HCFSEARCH QH_HCLLIST QH_HCMMEM QH_HCOOBJECT QH_HCSSET QH_HCSSIGNAL QH_HCSPLAYGROUND QH_HCSSPRITE Notes This function does not validate the accessability of the memory corresponding to lhHandle. Thus, a value that specifies an invalid memory location will cause the application to trap. Related information o CmnQueryHandleInfo ═══ 3.2. CmnQueryHandleInfo ═══ CmnQueryHandleInfo Purpose This function returns information about the specified handle. Syntax (BOOL)CmnQueryHandleInfo(lhHandle,pvInfo); Parameters lhHandle (LHANDLE) - specifies the handle to query. pvInfo (PVOID) - points to a handle-specific structure to be initialized. On return, this points to the initialized structure. Returns This function returns TRUE if the function is successful, or FALSE otherwise. Notes What pvInfo points to depends on the type of the handle specified: Handle type Buffer type HCCCONNECT pvInfo should point to a CCCONNECTINFO structure HCLLIST pvInfo should point to a CLLISTINFO structure HCMMEM pvInfo should point to a CMMEMINFO structure HCOOBJECT pvInfo should point to a COOBJECTINFO structure HCSSET pvInfo should point to a CSSETINFO structure Related information o CCCONNECTINFO data type o CLLISTINFO data type o CMMEMINFO data type o COOBJECTINFO data type o CSSETINFO data type o CmnQueryHandle o CmnSetHandleInfo ═══ 3.3. CmnQueryVersion ═══ CmnQueryVersion Purpose This function returns the major, minor, and revision numbers of the library. Syntax (VOID)CmnQueryVersion(pusMajor,pusMinor,pusRev); Parameters pusMajor (PUSHORT) - points to the variable to receive the major version number pusMinor (PUSHORT) - points to the variable to receive the minor version number pusRev (PUSHORT) - points to the variable to receive the revision version number ═══ 3.4. CmnSetHandleInfo ═══ CmnSetHandleInfo Purpose This function sets certain attributes about the specified handle. Syntax (BOOL)CmnSetHandleInfo(lhHandle,pvInfo); Parameters lhHandle (LHANDLE) - specifies the handle to query. pvInfo (PVOID) - points to a handle-specific structure containing the information to set. Returns This function returns TRUE if the function is successful, or FALSE otherwise. Notes What pvInfo points to depends on the type of the handle specified: Handle type Buffer type HCCCONNECT pvInfo should point to a CCCONNECTINFO structure Related information o CCCONNECTINFO data type o CmnQueryHandle o CmnQueryHandleInfo ═══ 4. Buffer routines ═══ The purpose of this group is to provide functionality that modifies entire buffers which can be comprised of any type of data. This group could eventually be expanded to provide a text buffer engine to be used in building editor applications. Listed below are the functions which comprise this group: o CmnBufCompressBytes o CmnBufDecompressBytes o CmnBufDecryptBytes o CmnBufEncryptBytes ═══ 4.1. CmnBufCompressBytes ═══ CmnBufCompressBytes Purpose This function attempts to compress the contents of a buffer. Syntax (BOOL)CmnBufCompressBytes(pbInBuf,ulSzInBuf,pbOutBuf,pulSzOutBuf); Parameters pbInBuf (PBYTE) - points to the buffer containing the data to be compressed. ulSzInBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. pbOutBuf (PBYTE) - points to the buffer to hold the compressed data. pulSzOutBuf (PULONG) - points to the variable specifying the size of the buffer pointed to by pbOutBuf. On return, the variable contains the size of the compressed data. Returns This function returns TRUE if successful, or FALSE otherwise. Notes CmnBufCompressBytes uses a run-length-encoding algorithm when compressing the data. While this algorithm is not expensive in CPU time consumed, it is not very good at compressing either and it is not guaranteed that the size of the compressed data will be less than the size of the original data. If you specify NULL for pbOutBuf, no data is written, but pulSzOutBuf will still be updated; so, you could specify NULL first to determine the size of the buffer needed before actually compressing the data. Related information o CmnBufDecompressBytes ═══ 4.2. CmnBufDecompressBytes ═══ CmnBufDecompressBytes Purpose This function decompresses the contents of a buffer which was compressed previously using CmnBufCompressBytes. Syntax (BOOL) CmnBufDecompressBytes(pbInBuf,ulSzInBuf,pbOutBuf,pulSzOutBuf); Parameters pbInBuf (PBYTE) - points to the buffer containing the data to be decompressed. ulSzInBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. pbOutBuf (PBYTE) - points to the buffer to hold the decompressed data. pulSzOutBuf (PULONG) - points to the variable specifying the size of the buffer pointed to by pbOutBuf. On return, the variable contains the size of the decompressed data. Returns This function returns TRUE if successful, or FALSE otherwise. Notes There is no error checking to insure that the buffer was compressed with CmnBufCompressBytes. This responsibility is left to the application designer. Related information o CmnBufCompressBytes ═══ 4.3. CmnBufDecryptBytes ═══ CmnBufDecryptBytes Purpose This function decrypts the contents of a buffer which was encrypted previously using CmnBufEncryptBytes. Syntax (BOOL)CmnBufDecryptBytes(pbInBuf,ulSzBuf,pbOutBuf); Parameters pbInBuf (PBYTE) - points to the buffer containing the data to be decrypted. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. pbOutBuf (PBYTE) - points to the buffer to contain the decrypted data. Returns This function returns TRUE if successful, or FALSE otherwise. Notes There is no error checking to insure that the buffer was encrypted with CmnBufEncryptBytes. This responsibility is left to the application designer. Related information o CmnBufEncryptBytes ═══ 4.4. CmnBufEncryptBytes ═══ CmnBufEncryptBytes Purpose This function encrypts a buffer using the NSS algorithm. Syntax (BOOL)CmnBufEncryptBytes(pbInBuf,ulSzBuf,pbOutBuf); Parameters pbInBuf (PBYTE) - points to the buffer containing the data to be encrypted. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. pbOutBuf (PBYTE) - points to the buffer to contain the encrypted data. Returns This function returns TRUE if successful, or FALSE otherwise. Notes NSS is an acronym for not-so-secure and describes the strength of the algorithm used. The encrypted data is always of the same length as the original data. It is suggested that this function be used in conjunction with the function CmnBufCompressBytes to result in data that will not so easily be decyphered. Related information o CmnBufDecryptBytes ═══ 5. Communication routines ═══ The purpose of this group is to provide easy to use communication routines for client/server application development. The bidirectional connections are implemented via named pipes and can thus work locally or over a LAN. A client simply opens a connection and starts reading and/or writing to it, while a server waits for a connection and reads/writes to a private connection which is derived from the "control connection" (see the pseudocode below). This yields three connection types: 1. Client 2. Server 3. Server-connect /* Client */ HCCCONNECT hccConnect; CmnComOpenConnection(...,&hccConnect); CmnComReadData(hccConnect,...); CmnComWriteData(hccConnect,...); CmnComSendControl(hccConnect,CSC_CTRL_CLOSE); CmnComCloseConnection(&hccConnect); /* ------------------------------------------------ */ /* Server */ HCCCONNECT hccServer; HCCCONNECT hccConnect; CmnComOpenConnection(...,&hccServer); CmnComWaitConnection(hccServer,&hccConnect); /****************************************************/ /* For peer-to-peer, we would close hccServer after */ /* establishing a data connection with a client */ /****************************************************/ CmnComReadData(hccConnect,...); CmnComWriteData(hccConnect,...); CmnComSendControl(hccConnect,CSC_CLOSE); CmnComCloseConnection(&hccServer); CmnComCloseConnection(&hccConnect); Using this implementation strategy has two advantages: 1) it is very easy to create client/server or peer-to-peer applications and 2) programmers familiar with TCP/IP will find this very familiar. Data is written in the form of packets, allowing for a handshaking protocol to be used by the functions. This insures that the other end receives the data written into the connection. Listed below are the functions which comprise this group: o CmnComCloseConnection o CmnComOpenConnection o CmnComQueryData o CmnComReadData o CmnComSendControl o CmnComWaitConnection o CmnComWriteData ═══ 5.1. CmnComCloseConnection ═══ CmnComCloseConnection Purpose Closes a connection. Syntax (COMERROR)CmnComCloseConnection(phccConnect) Parameters phccConnect (PHCCCONNECT) - points to the variable specifying the handle of the connection. On return, this variable contains NULL. Returns This function returns one of the following values: COM_ERR_NOERROR COM_ERR_BADHANDLE Notes Use CmnComCloseConnection to close a specific connection. Note that closing a server connection does not close any private data connections that were established from the server connection. It is recommended to send a CSC_CLOSE control code to indicate to the application on the other side that the connection is about to be closed. Related information o HCCCONNECT data type o CmnComOpenConnection o CmnComSendControl ═══ 5.2. CmnComOpenConnection ═══ CmnComOpenConnection Purpose Creates a new connection handle based upon the information provided. Syntax (COMERROR)CmnComOpenConnection(pcoiInfo,phccConnect) Parameters pcoiInfo (PCCOPENINFO) - points to a CCOPENINFO structure which describes the connection to be created. This parameter is required. On return, the usAttr field specifies the type of connection that was established (e.g. client, server, or server-connect). phccConnect (PHCCCONNECT) - points to the variable which receives the new connection handle. Returns This function returns one of the following values: COM_ERR_NOERROR COM_ERR_BADARGUMENT COM_ERR_CC_CLOSE COM_ERR_CC_RESET COM_ERR_ERROR COM_ERR_INITFAILED COM_ERR_NOCONNECTION COM_ERR_NOMEMORY COM_ERR_READFAILED COM_ERR_TIMEOUT Notes Use CmnComOpenConnection to create a new connection. If the achMachine field of the CCOPENINFO structure is empty, then the connection is a local one. Note that the timeout value (the lTimeout field) is changeable via CmnSetHandleInfo. This allows you to set a timeout now until a connection is established and then change it later for data retrieval. Server connections cannot be read from or written to. Instead, they are used to call CmnComWaitConnection to establish a server-connect connection for data transfer. Related information o CCOPENINFO data type o HCCCONNECT data type o CmnComCloseConnection o CmnComWaitConnection ═══ 5.3. CmnComQueryData ═══ CmnComQueryData Purpose Checks to see if data is available for reading. Syntax (COMERROR)CmnComQueryData(hccConnect,pulData) Parameters hccConnect (HCCCONNECT) - specifies the connection handle. pulData (PULONG) - points to the variable which receives the number of bytes available. Returns This function returns one of the following values: COM_ERR_NOERROR COM_ERR_BADHANDLE Notes Use CmnComQueryData to determine if data is available on the connection for reading. Note that if the application writes data to the connection and the receiving end does not read the data before this function is called, pusData will return 0 bytes available. Related information o HCCCONNECT data type o CmnComReadData o CmnComWriteData ═══ 5.4. CmnComReadData ═══ CmnComReadData Purpose Reads data from a connection and sends an acknowledgement to the other end of the connection. Syntax (COMERROR)CmnComReadData(hccConnect,pvBuf,pulSzBuf) Parameters hccConnect (HCCCONNECT) - specifies the connection handle. pvBuf (PVOID) - points to the buffer to receive the data. pulSzBuf (PULONG) - points to the variable specifying the size of the buffer pointed to by pvBuf. On return, this variable contains the number of bytes actually read from the connection. Returns This function returns one of the following values: COM_ERR_NOERROR COM_ERR_BADDATA COM_ERR_BADHANDLE COM_ERR_BUFFERTOOLARGE COM_ERR_CC_CLOSE COM_ERR_CC_RESET COM_ERR_ERROR COM_ERR_INITFAILED COM_ERR_READFAILED COM_ERR_TIMEOUT Notes Use CmnComReadData to read data from a connection. Note that if the buffer specified is not large enough to contain the data in the current packet, the additional bytes are discarded. Thus, if a predetermined, fixed data length is not used, it is highly recommended that CmnComQueryData is called to retrieve the size of the current packet. If there is no data at the front of the connection for the application to read, this function waits until there is data or until a timeout occurs. For 16-bit applications, there is a limit of 61440 bytes that can be read in one call. Note that if the other end sends a control code, no data is placed into pvBuf but the appropriate COM_ERR_CC_* code is returned instead. Related information o HCCCONNECT data type o CmnComQueryData o CmnComSendControl o CmnComWriteData ═══ 5.5. CmnComSendControl ═══ CmnComSendControl Purpose This function sends a control code to the other end of the connection. Syntax (COMERROR)CmnComSendControl(hccConnect,ulCtrlCode) Parameters hccConnect (HCCCONNECT) - specifies the connection handle. ulCtrlCode (ULONG) - specifies a CSC_* control code. Returns This function returns one of the following values: COM_ERR_NOERROR COM_ERR_BADACK COM_ERR_BADCONTROL COM_ERR_BADHANDLE COM_ERR_NOTIMPLEMENTED COM_ERR_WRITEFAILED Notes Use CmnComSendControl to send a control code to the other end of the connection. "Control codes" are predefined data packets which indicate that a particular action is to be performed. For CSC_CLOSE control codes, it is conceivable that the other end of the connection is able to close the connection before the packet acknowledgement is read by this end. Thus, a return value of COM_ERR_BADACK should be accounted for in your application code. It is highly recommended that a CSC_CLOSE control code is sent before closing the connection to allow the other end to perform any necessary cleanup (such as reading any data that is expected). Note that this function unconditionally waits for an acknowledgement. Related information o CSC_ constants o HCCCONNECT data type ═══ 5.6. CmnComWaitConnection ═══ CmnComWaitConnection Purpose Waits for a connection from a client. Syntax (COMERROR)CmnComWaitConnection(hccServer,phccConnect) Parameters hccServer (HCCCONNECT) - specifies the server connection handle. phccConnect (PHCCCONNECT) - points to the variable which receives the created server-connect connection handle. Returns This function returns one of the following values: COM_ERR_NOERROR COM_ERR_BADHANDLE COM_ERR_ERROR COM_ERR_INITFAILED COM_ERR_NOMEMORY COM_ERR_NONEFREE COM_ERR_NOTSERVER COM_ERR_TIMEOUT COM_ERR_WRITEFAILED Notes Use CmnComWaitConnection to listen for a connection by a client. When this happens, a server-connect connection is created for data exchange between the applications. This allows the hccServer handle to continue to listen for other connections via subsequent calls to this function. If peer-to-peer communications are desired, CmnComCloseConnection can be called to close the server connection so that no further data connections are established. A server may have up to 256 associated server-connect connections spawned from it, but this may exceed a system-imposed limit. Related information o HCCCONNECT data type o CmnComCloseConnection ═══ 5.7. CmnComWriteData ═══ CmnComWriteData Purpose Writes data to a connection and waits for an acknowledgement from the other end of the connection. Syntax (COMERROR)CmnComWriteData(hccConnect,pvBuf,ulSzBuf) Parameters hccConnect (HCCCONNECT) - specifies the connection handle. pvBuf (PVOID) - points to the buffer containing the data to write. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pvBuf. Returns This function returns one of the following values: COM_ERR_NOERROR COM_ERR_BADACK COM_ERR_BADHANDLE COM_ERR_BUFFERTOOLARGE COM_ERR_WRITEFAILED Notes Use CmnComWriteData to write data to a connection. Acknowledgement receipt is handled transparently by the function. For 16-bit applications, there is a limit of 61440 bytes that can be written in one call. Related information o HCCCONNECT data type o CmnComReadData ═══ 6. Debugging routines ═══ The purpose of this group is to provide aid in debugging your applications. While they are not anything spectacular, I have found them helpful from time to time. Listed below are the functions which comprise this group: o CmnDbgWriteBinary o CmnDbgWriteRecord o CmnDbgWriteText ═══ 6.1. CmnDbgWriteBinary ═══ CmnDbgWriteBinary Purpose This function writes the contents of a buffer to a file. Syntax (SHORT)CmnDbgWriteBinary(pvFile, usFileType, pvBuf, usSzBuf); Parameters pvFile (PVOID) - points to either the file name or a FILE structure (as defined in ). usFileType (USHORT) - specifies a DWT_TYPE_ constant describing the contents of pvFile. pvBuf (PVOID) - points to the buffer to be written. usSzBuf (USHORT) - specifies the size of the buffer pointed to by pvBuf. Returns This function returns the number of bytes successfully written, or DWT_ERROR otherwise. Notes Use CmnDbgWriteBinary to write the contents of a buffer to a specific file. The format of the output is a combination of hexadecimal on the left side with ASCII representation on the right with a vertical line separating the two. Unprintable characters (as defined by the function isprint) are displayed as periods in the ASCII output. Related information o DWT_TYPE_ constants o CmnDbgWriteText ═══ 6.2. CmnDbgWriteRecord ═══ CmnDbgWriteRecord Purpose This function writes the contents of a structure to a file. Syntax (SHORT)CmnDbgWriteRecord(pvFile, usFileType, pcFormat, usNumRecs, pbBuf); Parameters pvFile (PVOID) - points to either the file name or a FILE structure (as defined in ). usFileType (USHORT) - specifies a DWT_TYPE_ constant describing the contents of pvFile. pcFormat (PCSLINEDESC) - points to an array of CSLINEDESC structures describing the format of the structure to be written. usNumRecs (USHORT) - specifies the number of records pointed to by pcFormat. pbBuf (PBYTE) - points to the structure to write. Returns This function returns the number of fields in the structure successfully written, or DWT_ERROR otherwise. Notes Use CmnDbgWriteRecord to write the contents of a record to a specific file. This function calls CmnDbgWriteText to actually write the results, so the file is guaranteed to be flushed after every field is output. Related information o DWT_TYPE_ constants o CSLINEDESC data type o CmnDbgWriteText ═══ 6.3. CmnDbgWriteText ═══ CmnDbgWriteText Purpose This function writes text to a specified file. Syntax (SHORT)CmnDbgWriteText(pvFile,usFileType,pchFmt,...); Parameters pvFile (PVOID) - points to either the file name or a FILE structure (as defined in ). usFileType (USHORT) - specifies a DWT_TYPE_ constant describing the contents of pvFile. pchFmt (PCHAR) - points to the format string (as in the C printf routine). ... (va_list) - specifies any additional arguments referred to by pchFmt Returns This function returns the number of characters successfully written, or DWT_ERROR otherwise. Notes Use CmnDbgWriteText to write information to a file. By specifying DWT_TYPE_FILE for usFileType, you can use a predefined stream (stdout, stderr) or any other file that is already opened. Specifying DWT_TYPE_NAME indicates that this function should open the file in append mode and close it before returning. o DWT_TYPE_ constants ═══ 7. File routines ═══ The purpose of this group is to provide functions which help you perform common tasks without a lot of the work. Listed below are the functions which comprise this group: o CmnFilCopyDiskette o CmnFilCreateSearch o CmnFilDestroySearch o CmnFilFormatDiskette o CmnFilQueryExtAttribute o CmnFilQueryLabel o CmnFilSearchFiles o CmnFilSetExtAttribute o CmnFilSplitFilename ═══ 7.1. CmnFilCopyDiskette ═══ CmnFilCopyDiskette Purpose This function copies the contents of a diskette onto another diskette. Syntax (BOOL)CmnFilCopyDiskette(chSrc,chDest,ulOptions,pfnCallback,pvUser); Parameters chSrc (CHAR) - specifies the source drive and can be upper- or lower-case. chDest (CHAR) - specifies the destination drive and can be upper- or lower-case. ulOptions (ULONG) - one or more FCD_OPT_* constants controlling the behavior of this function. pfnCallback (PFNDISKIO) - points to a callback function. See below for more information. pvUser (PVOID) - pointer to user data which is passed to pfnCallback. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnFilCopyDiskette to copy one diskette onto another. The power of this function is in the use of pfnCallback; this callback function is called by CmnFilCopyDiskette in various times for various reasons. See the items listed below for more information on the specifics of each constant. Related information o FCD_TYPE_ constants o FCD_MSG_ constants o FCD_ERR_ constants o PFNDISKIO function ═══ 7.2. CmnFilCreateSearch ═══ CmnFilCreateSearch Purpose This function creates a search handle for use in subsequent calls to CmnFilSearchFiles. Syntax (BOOL)CmnFilCreateSearch(pchMask,ulAttr,phcSearch); Parameters pchMask (PCHAR) - points to the file mask to be used when searching for the files. ulAttr (ULONG) - specifies a combination of FCS_ATTR_ constants which specify the types of files to search for. phcSearch (PHCFSEARCH) - on return, this points to the variable containing the created search handle. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnFilCreateSearch to create a search handle for use in calls to CmnFilSearchFiles. Note that, unlike DosFindFirst, "normal" files (those with no special attributes) are not searched for unless FCS_ATTR_NORMAL is specified in ulAttr. Related information o FCS_ATTR_ constants o HCFSEARCH data type o CmnFilSearchFiles ═══ 7.3. CmnFilDestroySearch ═══ CmnFilDestroySearch Purpose This function destroys a search handle created by CmnFilCreateSearch. Syntax (BOOL)CmnFilDestroySearch(hcSearch); Parameters phcSearch (PHCFSEARCH) - points to the variable specifying the search handle to destroy. On return, this variable contains NULL. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnFilDestroySearch to free any resources consumed by the search functions. Related information o HCFSEARCH data type o CmnFilCreateSearch ═══ 7.4. CmnFilFormatDiskette ═══ CmnFilFormatDiskette Purpose This function formats a diskette. Syntax (BOOL)CmnFilFormatDiskette(chDrive,pfiInfo,pfnCallback,pvUser); Parameters chDrive (CHAR) - specifies the drive in which the diskette to be formatted is placed. pfiInfo (PCFFORMATINFO) - points to a CFFORMATINFO structure specifying the format parameters to be used. If NULL the parameters for the diskette are used (if the diskette is already formatted), or the defaults for the drive are used (if the diskette is not already formatted). pfnCallback (PFNDISKIO) - points to a callback function. See below for more information. pvUser (PVOID) - pointer to user data which is passed to pfnCallback. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnFilFormatDiskette to format a diskette. The power of this function is in the use of pfnCallback; this callback function is called by CmnFilFormatDiskette in various times for various reasons. See the items listed below for more information on the specifics of each constant. The boot sector that is written to the diskette consists of a program at offset 0x40 (which is jumped to by the first two bytes of the boot sector), which loads and displays an ASCIIZ string beginning at offset 0x80. The default message placed there is a NULL-string. To specify your own string to be displayed, you need to read track 0, head 0, sector 0, and copy your string into the buffer containing the sector's data at the correct offset, and then write the new contents to track 0, head 0, sector 0. When determining the string to be written, be aware that - on the rarely found machines with single-head, single-density floppy drives - you only have 30 bytes (including the terminating 0) for the string's contents. Related information o FCD_TYPE_ constants o FCD_MSG_ constants o FCD_ERR_ constants o CFFORMATINFO data type o PFNDISKIO function ═══ 7.5. CmnFilQueryExtAttribute ═══ CmnFilQueryExtAttribute Purpose This function queries the value of an extended attribute written by CmnFilSetExtAttribute. Syntax (BOOL)CmnFilQueryExtAttribute(pchFile, pchVendor, pchAppl, pchName, pusAttr, pbValue, pusSzValue); Parameters pchFile (PCHAR) - points to the name of the file containing the extended attributes to query. pchVendor (PCHAR) - points to the name of the vendor whose application wrote the extended attribute or an FEA_ constant. pchAppl (PCHAR) - points to the name of the application which wrote the extended attribute. pchName (PCHAR) - points to the name of the extended attribute. pusAttr (PUSHORT) - points to the attribute of the extended attribute. pbValue (PBYTE) - points to a buffer to receive the results. On return, the buffer contains the value of the extended attribute. pusSzValue (PUSHORT) - points to a variable specifying the size of pbValue. On return, this points to the number of bytes copied to the buffer. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnFilQueryExtAttribute to query an extended attribute of a file. Because this call (and CmnFilSetExtAttribute) enforces the convention stated in the IBM Programming Toolkit's "Programming Guide", this function is only guaranteed to return meaningful results if the extended attribute was originally written by CmnFilSetExtAttribute. If an FEA_ constant is specified for pchVendor, pchAppl and pchName are ignored. Related information o FEA_ constants o CmnFilSetExtAttribute ═══ 7.6. CmnFilQueryLabel ═══ CmnFilQueryLabel Purpose This function returns the label on the diskette in the specified drive. Syntax (BOOL)CmnFilQueryLabel(chDrive,pchLabel); Parameters chDrive (CHAR) - specifies the drive to query. pchLabel (PCHAR) - points to the buffer to hold the label. On return, this buffer holds the diskette label if successful. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnFilQueryLabel to determine the label of the diskette in the specified drive. This function will not cause a "hard error" popup to appear if no diskette is in the drive; instead, this function will return FALSE. ═══ 7.7. CmnFilSearchFiles ═══ CmnFilSearchFiles Purpose This function returns the next file found that has the characteristics specified when the search handle was created. Syntax (LONG)CmnFilSearchFiles(hcSearch,pchBuf,ulSzBuf); Parameters hcSearch (HCFSEARCH) - specifies the search handle. pchBuf (PCHAR) - points to a buffer to receive the results. On return, the buffer contains the fully qualified name of the next file found. ulSzBuf (ULONG) - specifies the size of pchBuf. Returns This function returns the attribute of the file found as a combination of FCS_ATTR_ constants if successful, FSF_NOFILES if no more files were found that match the criteria, or FSF_ERROR if an error occurred. Notes Use CmnFilSearchFiles to search for the next file that exactly matches the criteria (file mask and attribute) specified in the search handle. Note that the attribute match must be exact (i.e. not a subset). For example, if file "A" has the archive, hidden, system, and read-only attributes set, it will not be found unless you specify all four of its attributes. Related information o FCS_ATTR_ constants o HCFSEARCH data type o CmnFilCreateSearch ═══ 7.8. CmnFilSetExtAttribute ═══ CmnFilSetExtAttribute Purpose This function writes an extended attribute to the specified file. Syntax (BOOL)CmnFilSetExtAttribute(pchFile, usAttr, pchVendor, pchAppl, pchName, pbValue, usSzValue); Parameters pchFile (PCHAR) - points to the name of the file containing the extended attributes to set. usAttr (USHORT) - points to the attribute of the extended attribute. pchVendor (PCHAR) - points to the name of the vendor whose application is writing the extended attribute or an FEA_ constant. pchAppl (PCHAR) - points to the name of the application which is writing the extended attribute. pchName (PCHAR) - points to the name of the extended attribute. pbValue (PBYTE) - points to a buffer containing the value of the extended attribute. usSzValue (USHORT) - specifies the size of pbValue. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnFilSetExtAttribute to write an extended attribute to a file. Since this function enforces the convention stated in the IBM Programming Toolkit's "Programming Guide", you should use CmnFilQueryExtAttribute to read the extended attribute when needed or insure that the code is aware of the added information written. Related information If an FEA_ constant is specified for pchVendor, pchAppl and pchName are ignored. o FEA_ constants o CmnFilQueryExtAttribute ═══ 7.9. CmnFilSplitFilename ═══ CmnFilSplitFilename Purpose This function splits a filename into its various components. Syntax (BOOL)CmnFilSplitFilename(pchFile,pchDrive,pchPath,pchName); Parameters pchFile (PCHAR) - points to the name of the file to be split pchDrive (PCHAR) - points to the buffer to receive the drive pchPath (PCHAR) - points to the buffer to receive the path pchName (PCHAR) - points to the buffer to receive the name Returns This function returns TRUE if successful, or FALSE otherwise. Notes pchDrive, pchPath, or pchName can be NULL if you are not interested in that component. pchDrive will always end in a colon (':'). pchPath will always end with a backslash ('\'). ═══ 8. Link-list routines ═══ The purpose of this group is to provide a complete linked list implementation which is limited only by the amount of memory in your system. I have defined a list to be a set of homogeneous items; thus, each item in the list is of a fixed size, which is declared when the list is created. Also, each item is doubly linked to provide quick access to any record from anywhere in the list. While this imposes an extra four bytes per record, the performance gains outweigh the additional memory required. Note that the links are hidden from the record; this is good in that if you want to have a list of integers, you do not have to define a structure to hold the integer and the links. Additionally, this hides the implementation of the list from the developer, so if it changes (and it has before) the developer does not need to do anything other than recompile. Listed below are the functions which comprise this group: o CmnLstAddRecord o CmnLstAddUniqueRecord o CmnLstCopyList o CmnLstCreateList o CmnLstDeleteList o CmnLstDeleteRecord o CmnLstDestroyList o CmnLstMoveRecord o CmnLstPruneList o CmnLstQueryRecord o CmnLstQueryRecordCount o CmnLstQueryRelative o CmnLstQuickSortList o CmnLstSearchRecord o CmnLstSortList o CmnLstTraverseList ═══ 8.1. CmnLstAddRecord ═══ CmnLstAddRecord Purpose This function adds a record to a linked list. Syntax (BOOL)CmnLstAddRecord(hclList,pvRecord,pfnSort,ppvResult); Parameters hclList (HCLLIST) - handle of the linked list to add to. pvRecord (PVOID) - points to the record to add. pfnSort (PFNRECCOMP) - points to the function which defines the sort order or an LAR_ constant. ppvResult (PVOID *) - points to the variable which receives the pointer to the inserted record. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnLstAddRecord to add a record to a linked list in the order defined by pfnSort. Since the linked list routines maintain their own copy of the records, ppvResult can optionally be specified to receive the pointer to the record within the list. pfnSort either points to a function which defines the placement of the record within the list or specifies an LAR_ constant. Note that if uniqueness must be enforced, you should instead use CmnLstAddUniqueRecord. Related information o LAR_ constants o HCLLIST data type o PFNRECCOMP function o CmnLstAddUniqueRecord ═══ 8.2. CmnLstAddUniqueRecord ═══ CmnLstAddUniqueRecord Purpose This function adds a record to a linked list only if it did not exist previously. Syntax (USHORT)CmnLstAddUniqueRecord(hclList, pvRecord, pfnSearch, pfnSort, ppvResult); Parameters hclList (HCLLIST) - handle of the linked list to add to. pvRecord (PVOID) - points to the record to add. pfnSearch (PFNRECCOMP) - points to the function which determines the equality of two records. pfnSort (PFNRECCOMP) - points to the function which defines the sort order. ppvResult (PVOID *) - points to the variable which receives the pointer to the inserted record. Returns This function returns LAUR_NOERROR if successful, LAUR_EXISTS if the record existed in the list prior to this call, or LAUR_ERROR if an error occurred. Notes Use CmnLstAddUniqueRecord to add a record in a linked list, while guaranteeing uniqueness within the list. Since the linked list routines maintain their own copy of the records, ppvResult can optionally be specified to receive the pointer to the record within the list. pfnSort either points to a function which defines the placement of the record within the list or specifies an LAR_ constant. pnfSearch points to a function which determines whether or not two records are equal and is required. Related information o LAR_ constants o HCLLIST data type o PFNRECCOMP function ═══ 8.3. CmnLstCopyList ═══ CmnLstCopyList Purpose This function copies the contents of one list into another list. Syntax (BOOL)CmnLstCopyList(hclList,hclCopy,pfnSort); Parameters hclList (HCLLIST) - handle of the linked list to copy to. hclCopy (HCLLIST) - handle of the linked list to copy from. pfnSort (PFNRECCOMP) - points to the function which defines the sort order. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnLstCopyList to copy the contents of one list into another. While this can be used to append a list to another, this function is frequently used to simply copy a list so that modifications to the original list can be recovered. Related information o HCLLIST data type ═══ 8.4. CmnLstCreateList ═══ CmnLstCreateList Purpose This function creates a linked list handle for use in subsequent calls to the CmnLst functions. Syntax (BOOL)CmnLstCreateList(usSzRecord,phclList); Parameters usSzRecord (USHORT) - specifies the size of each record in the linked list. phclList (PHCLLIST) - points to the variable which receives the created linked list handle. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnLstCreateList to create a linked list handle which can be used in other CmnLst functions. Note that only linked lists of fixed record size are supported, although specifying the maximum size of any record and then storing the actual size in the record itself would work (albeit very memory-inefficient). Since the records do not contain the link information directly, do not specify this in usSzRecord. Related information o HCLLIST data type o CmnLstDestroyList ═══ 8.5. CmnLstDeleteList ═══ CmnLstDeleteList Purpose This function deletes the contents of a linked list. Syntax (BOOL)CmnLstDeleteList(hclList); Parameters hclList (HCLLIST) - handle of the linked list to delete. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnLstDeleteList to delete the contents of a linked list. Note that the list still "exists" after this call; it is simply emptied of its contents. To destroy a list, use CmnLstDestroyList. Related information o HCLLIST data type o CmnLstDestroyList ═══ 8.6. CmnLstDeleteRecord ═══ CmnLstDeleteRecord Purpose This function deletes a record from a linked list. Syntax (BOOL)CmnLstDeleteRecord(hclList,pvRecord); Parameters hclList (HCLLIST) - handle of the linked list to delete from. pvRecord (PVOID) - points to the record to delete. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnLstDeleteRecord to delete a specific record from a linked list. This function adjusts the links in the list and frees the memory consumed by the record (but does not free any memory which is pointed to by any fields in the record). To delete the entire list, use CmnLstDeleteList. Related information o HCLLIST data type o CmnLstDeleteList ═══ 8.7. CmnLstDestroyList ═══ CmnLstDestroyList Purpose This function deletes the contents of a linked list and destroys the handle to the linked list. Syntax (BOOL)CmnLstDestroyList(phclList); Parameters phclList (PHCLLIST) - points to the variable specifying the handle of the linked list to delete. On return, this variable contains NULL. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnLstDestroyList to destroy a linked list handle. All records are delete via a call to CmnLstDeleteList before destroying the handle. Related information o HCLLIST data type o CmnLstCreateList o CmnLstDeleteList ═══ 8.8. CmnLstMoveRecord ═══ CmnLstMoveRecord Purpose This function moves a record to a position relative to another record. Syntax (BOOL)CmnLstMoveRecord(hclList,pvMove,pvWhere,sRelative); Parameters hclList (HCLLIST) - handle of the linked list. pvMove (PVOID) - pointer to the record to move pvWhere (PVOID) - pointer to the record specifying the new location sRelative (SHORT) - either LQR_PREVIOUS or LQR_NEXT specifying immediately before or after pvWhere, respectively. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnLstMoveRecord to move a record before or after another record in a linked list. Related information o HCLLIST data type ═══ 8.9. CmnLstPruneList ═══ CmnLstPruneList Purpose This function traverses a linked list and deletes the records that meet the specified criteria. Syntax (BOOL)CmnLstPruneList(hclList,pvRecord,pfnSearch); hclList (HCLLIST) - handle of the linked list to prune. pvSearch (PVOID) - points to a buffer specifying the search criteria. This is passed to pfnSearch as the second parameter. pfnSearch (PFNRECCOMP) - points to a function which determines whether or not a record matches the criteria. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnLstPruneList to remove only those records which meet a specific set of criteria from a linked list. This is typically used after calling CmnLstCopyList to remove all but the records of interest from the copied list. Related information o HCLLIST data type o PFNRECCOMP function o CmnLstSearchRecord ═══ 8.10. CmnLstQueryRecord ═══ CmnLstQueryRecord Purpose This function returns a pointer to the specified element in a linked list. Syntax (PVOID)CmnLstQueryRecord(hclList,sNumRecord); Parameters hclList (HCLLIST) - handle of the linked list to query. sNumRecord (SHORT) - specifies the 0-based index of the record desired. Returns This function returns a pointer to the desired record if successful, or NULL otherwise. Notes Use CmnLstQueryRecord to query a specific record number from a linked list. Note that, if the record desired precedes or follows a previously queried record, it is much more efficient to instead use CmnLstQueryRelative. This is an especially prominent condition in loop-based processing: usNumRecs=CmnLstQueryRecordCount(hclList); for (usIndex=0; usIndexxLeft=(current x position) prclRect->yBottom=(current y position) prclRect->xRight=prclRect->xLeft + (width of the original bitmap passed to CmnSprCreateSprite) - 1 prclRect->yTop=prclRect->yBottom + (height of the original bitmap passed to CmnSprCreateSprite) - 1 Related information o HCSSPRITE data type o CmnSprAddSprite o CmnSprQuerySpritePosition o CmnSprQuerySpriteSize o CmnSprQuerySpriteVisibility o CmnSprRemoveSprite o CmnSprSetSpritePosition o CmnSprSetSpriteVisibility ═══ 13.13. CmnSprQuerySpriteSize ═══ CmnSprQuerySpriteSize Purpose This function returns the size of the sprite. Syntax (SPRERROR)CmnSprQuerySpriteSize(hsSprite,pszlSize); Parameters hsSprite (HCSSPRITE) - handle of the sprite instance. pszlSize (PSIZEL) - points to the variable to receive the size of the sprite. Returns This function returns one of the following values: SPR_ERR_NOERROR SPR_ERR_BADHANDLE Notes Since the size of a sprite is static, this is the only function returning the value of a sprite characteristic which does not require the sprite to belong to a playground. Related information o HCSSPRITE data type o CmnSprAddSprite o CmnSprQuerySpritePosition o CmnSprQuerySpriteRect o CmnSprQuerySpriteVisibility o CmnSprRemoveSprite o CmnSprSetSpritePosition o CmnSprSetSpriteVisibility ═══ 13.14. CmnSprQuerySpriteVisibility ═══ CmnSprQuerySpriteVisibility Purpose This function returns the visibility of the sprite. Syntax (SPRERROR)CmnSprQuerySpriteVisibility(hsSprite,pbVisible); Parameters hsSprite (HCSSPRITE) - handle of the sprite instance. pbVisible (PBOOL) - points to the variable to receive the visibility state of the sprite. Returns This function returns one of the following values: SPR_ERR_NOERROR SPR_ERR_BADHANDLE SPR_ERR_HASNOPLAYGROUND Notes The sprite must belong to a playground to have a visibility state associated with it. Related information o HCSSPRITE data type o CmnSprAddSprite o CmnSprQuerySpritePosition o CmnSprQuerySpriteRect o CmnSprQuerySpriteSize o CmnSprRemoveSprite o CmnSprSetSpritePosition o CmnSprSetSpriteVisibility ═══ 13.15. CmnSprQueryUpdateFlag ═══ CmnSprQueryUpdateFlag Purpose This function returns the value of the update flag of a playground. Syntax (SPRERROR)CmnSprQueryUpdateFlag(hpgPlay,pbUpdate); Parameters hpgPlay (HCSPLAYGROUND) - handle of the playground instance. pbUpdate (PBOOL) - points to the variable to receive the update flag of the playground. Returns This function returns one of the following values: SPR_ERR_NOERROR SPR_ERR_BADHANDLE Related information o HCSPLAYGROUND data type o CmnSprSetUpdateFlag ═══ 13.16. CmnSprRemoveSprite ═══ CmnSprRemoveSprite Purpose This function removes a sprite from a playground. Syntax (SPRERROR)CmnSprRemoveSprite(hpgPlay,hsSprite); Parameters hpgPlay (HCSPLAYGROUND) - handle of the playground instance. hsSprite (HCSSPRITE) - handle of the sprite instance. Returns This function returns one of the following values: SPR_ERR_NOERROR SPR_ERR_BADHANDLE SPR_ERR_HASNOPLAYGROUND Notes This function must be called before the sprite can be destroyed. Related information o HCSPLAYGROUND data type o HCSSPRITE data type o CmnSprAddSprite o CmnSprCreateSprite o CmnSprDestroySprite ═══ 13.17. CmnSprSetPlaygroundBack ═══ CmnSprSetPlaygroundBack Purpose This function sets the bitmap to be used for the background. Syntax (SPRERROR)CmnSprSetPlaygroundBack(hpgPlay,hbmNew,phbmOld); Parameters hpgPlay (HCSPLAYGROUND) - handle of the playground instance. hbmNew (HBITMAP) - handle of the new background bitmap. phbmOld (HBITMAP *) - points to the variable to receive the handle of current background bitmap. This may be NULL. Returns This function returns one of the following values: SPR_ERR_NOERROR SPR_ERR_BADHANDLE Notes The playground also relinquishes ownership of the current background bitmap, meaning it becomes the application's responsibility to insure it is deleted before the application exits. Related information o HCSPLAYGROUND data type o CmnSprQueryPlaygroundBack o CmnSprQueryPlaygroundColor o CmnSprQueryPlaygroundSize o CmnSprSetPlaygroundColor o CmnSprSetPlaygroundSize ═══ 13.18. CmnSprSetPlaygroundColor ═══ CmnSprSetPlaygroundColor Purpose This function sets the current background color. Syntax (SPRERROR)CmnSprSetPlaygroundColor(hpgPlay,lBackColor); Parameters hpgPlay (HCSPLAYGROUND) - handle of the playground instance. lBackColor (LONG) - specifies the new background color. Returns This function returns one of the following values: SPR_ERR_NOERROR SPR_ERR_BADHANDLE SPR_ERR_HASBACKGROUND Notes If the playground has a background bitmap, this function fails with error SPR_ERR_HASBACKGROUND since the two properties are mutual exclusive. Related information o HCSPLAYGROUND data type o CmnSprQueryPlaygroundBack o CmnSprQueryPlaygroundColor o CmnSprQueryPlaygroundSize o CmnSprSetPlaygroundBack o CmnSprSetPlaygroundSize ═══ 13.19. CmnSprSetPlaygroundSize ═══ CmnSprSetPlaygroundSize Purpose This function sets the size of the playground. Syntax (SPRERROR)CmnSprSetPlaygroundSize(hpgPlay,pszlSize); Parameters hpgPlay (HCSPLAYGROUND) - handle of the playground instance. pszlSize (PSIZEL) - points to the variable specifying the new size of the playground. Returns This function returns one of the following values: SPR_ERR_NOERROR SPR_ERR_BADHANDLE SPR_ERR_HASBACKGROUND Notes If the playground has a background bitmap, this function fails with error SPR_ERR_HASBACKGROUND since the two properties are mutual exclusive. Related information o HCSPLAYGROUND data type o CmnSprQueryPlaygroundBack o CmnSprQueryPlaygroundColor o CmnSprQueryPlaygroundSize o CmnSprSetPlaygroundColor o CmnSprSetPlaygroundSize ═══ 13.20. CmnSprSetSpritePosition ═══ CmnSprSetSpritePosition Purpose This function sets the position of the sprite. Syntax (SPRERROR)CmnSprSetSpritePosition(hpsDraw,hsSprite,pptlNew); Parameters hpsDraw (HPS) - handle of the presentation space to draw within. hsSprite (HCSSPRITE) - handle of the sprite instance. pptlNew (PPOINTL) - points to the variable specifying the new position. Returns This function returns one of the following values: SPR_ERR_NOERROR SPR_ERR_BADHANDLE SPR_ERR_HASNOPLAYGROUND Notes The algorithm used by this function is optimized to remove flicker when the bounding rectangle of the sprite at the current position overlaps the bounding rectangle of the sprite at the new position. If the sprite is not visible, this function returns SPR_ERR_NOERROR. Related information o HCSSPRITE data type o CmnSprQuerySpritePosition o CmnSprQuerySpriteRect o CmnSprQuerySpriteSize o CmnSprQuerySpriteVisibility o CmnSprSetSpriteVisibility ═══ 13.21. CmnSprSetSpriteVisibility ═══ CmnSprSetSpriteVisibility Purpose This function sets the visibility state of a sprite. Syntax (SPRERROR)CmnSprSetSpriteVisibility(hpsDraw,hsSprite,bVisible); Parameters hpsDraw (HPS) - handle of the presentation space to draw within. hsSprite (HCSSPRITE) - handle of the sprite instance. bVisible (BOOL) - specifies the new visibility state. Returns This function returns one of the following values: SPR_ERR_NOERROR SPR_ERR_BADHANDLE SPR_ERR_HASNOPLAYGROUND Related information o HCSSPRITE data type o CmnSprQuerySpritePosition o CmnSprQuerySpriteRect o CmnSprQuerySpriteSize o CmnSprQuerySpriteVisibility o CmnSprSetSpritePosition ═══ 13.22. CmnSprSetUpdateFlag ═══ CmnSprSetUpdateFlag Purpose This function sets the update flag of the playground. Syntax (SPRERROR)CmnSprSetUpdateFlag(hpgPlay,bUpdate); Parameters hpgPlay (HCSPLAYGROUND) - handle of the playground instance. bUpdate (BOOL) - specifies the new update flag value. Returns This function returns one of the following values: SPR_ERR_NOERROR SPR_ERR_BADHANDLE Notes The update flag determines if any drawing actually takes place when any of the functions requiring a presentation space handle are called. Related information o HCSPLAYGROUND data type o CmnSprQueryUpdateFlag ═══ 14. String routines ═══ The purpose of this group is to provide functions that manipulate strings which and are not provided by the C run time library. Listed below are the functions which comprise this group: o CmnStrConvertToNumber o CmnStrPadString o CmnStrParseCommandLine o CmnStrParseLine o CmnStrQueryWord o CmnStrQueryWordCount o CmnStrQueryWordLength o CmnStrQueryWordPosition o CmnStrStripSpace ═══ 14.1. CmnStrConvertToNumber ═══ CmnStrConvertToNumber Purpose This function converts a string into its numerical equivalent. Syntax (BOOL)CmnStrConvertToNumber(pchString,pvResult,usType); Parameters pchString (PCHAR) - points to the string to convert. pvResult (PVOID) - points to the buffer to receive the result. The size of this buffer depends on the SCTN_TYPE_ constant specified. usType (USHORT) - specifies a combination of one SCTN_TYPE_ constant and one SCTN_ATTR_ constant. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnStrConvertToNumber to convert a string to a number. This is preferable to atoi (atol, etc.) because this function returns a definitive indicator of success, whereas the ANSI functions simply return 0 when an error occurs (and this could be a valid value as well). Related information o SCTN_ constants ═══ 14.2. CmnStrPadString ═══ CmnStrPadString Purpose This function pads a string with a specified character. Syntax (BOOL)CmnStrPadString(pchString,usSide,usLength,chPad); Parameters pchString (PCHAR) - points to the string to pad. usSide (USHORT) - specifies the side to pad on as an SPS_ constant. usLength (USHORT) - specifies the desired length of the string. chPad (CHAR) - specifies the character to pad with. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnStrPadString to pad a string to a specified length. Related information o SPS_ constants ═══ 14.3. CmnStrParseCommandLine ═══ CmnStrParseCommandLine Purpose This function parses the command line arguments. Syntax (BOOL)CmnStrParseCommandLine(ppchArgs, usNumArgs, pccdFormat, usNumSwitches, pfnError); Parameters ppchArgs (PCHAR *) - points to an array of pointers to the command line arguments. usNumArgs (USHORT) - specifies the number of arguments pointed to by ppchArgs. pccdFormat (PCSCMDDESC) - points to an array of CSCMDDESC structures describing the valid command line arguments. usNumSwitches (USHORT) - specifies the number of structures pointed to by pccdFormat. pfnError (PFNCMDERR) - points to a function which is called when an error occurs. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnStrParseCommandLine to parse the command line arguments passed to the application. For each argument that is described in pccdFormat, the corresponding function is called with the arguments to the command line argument (if any). pfnError is called whenever an error occurs while processing the command line. While this could be a syntax error (returned by the argument processing function), it could also be another error type (out of memory, etc.). Related information o CSCMDDESC data type o PFNCMDERR function ═══ 14.4. CmnStrParseLine ═══ CmnStrParseLine Purpose This function parses a line of data containing fixed position, fixed length fields. Syntax (SHORT)CmnStrParseLine(pchLine,acFormat,usNumRecs,pbBuf); Parameters pchLine (PCHAR) - points to the line to parse. pcFormat (PCSLINEDESC) - points to an array of CSLINEDESC structures describing the fields in the line. On return, the usType field indicates whether or not the field was empty. usNumRecs (USHORT) - specifies the number of structures pointed to by pcFormat. pbBuf (PBYTE) - points to the buffer to receive the results. On return, the buffer is initialized to the native equivalents of the fields (numeric, string, etc.). Returns This function returns the number of fields successfully parsed, or SPL_ERROR if an error occurred. Notes Use CmnStrParseLine to parse a line consisting of fixed position, fixed length fields similar to the sscanf function. For example, supposing pchLine points to the following data: 12345This is a string678.90 Also, pcFormat points to four CSLINEDESC structures, containing the following values: { { 0, 5, SPL_TYPE_LONG }, { 21, 6, SPL_TYPE_FLOAT }, { 5, 16, SPL_TYPE_STRING }, { 28, 4, SPL_TYPE_BYTE } } pbBuf points to a structure defined as follows: typedef struct { LONG lField1; float fField2; CHAR achField3[17]; BYTE bField4; } BUF, FAR *PBUF; On exit, pbBuf points to the initialized structure containing 12345, 678.9, "This is a string", and (undefined), and the usType field of the CSLINEDESC structures will be SPL_FOUND, SPL_FOUND, SPL_FOUND, and SPL_NOT_FOUND (to indicate that there was not fourth field). It is imperative to note that if you are using this function, all structures initialized by this function must be "unaligned", i.e. no alignment of fields should be done by the compiler. If you forget to specify this, unpredictable results will occur. Related information o SPL_ constants o CSLINEDESC data type ═══ 14.5. CmnStrQueryWord ═══ CmnStrQueryWord Purpose This function returns the specified word in a string. Syntax (BOOL)CmnStrQueryWord(pchLine,sWord,pchWord,usSzWord); Parameters pchLine (PCHAR) - points to the line to retrieve the word from. sWord (SHORT) - specifies the 0-based word number to retrieve. pchWord (PCHAR) - points to the buffer to receive the result. On return, the buffer contains the word retrieved. usSzWord (USHORT) - specifies the size of the buffer pointed to by pchWord. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnStrQueryWord to retrieve a word from a line. A word is defined as a sequence of letters, digits, and/or punctuation, delimited by whitespace. Related information o CmnStrQueryWordCount o CmnStrQueryWordLength o CmnStrQueryWordPosition ═══ 14.6. CmnStrQueryWordCount ═══ CmnStrQueryWordCount Purpose This function queries the number of words in a line. Syntax (USHORT)CmnStrQueryWordCount(pchLine); Parameters pchLine (PCHAR) - points to the line to query. Returns This function returns the number of words in the specified line. Notes Use CmnStrQueryWordCount to query the number of words in a line of ASCII data. Related information o CmnStrQueryWord o CmnStrQueryWordLength o CmnStrQueryWordPosition ═══ 14.7. CmnStrQueryWordLength ═══ CmnStrQueryWordLength Purpose This function queries the length of a specified word in a line. Syntax (SHORT)CmnStrQueryWordLength(pchLine,sWord); Parameters pchLine (PCHAR) - points to the line to query. sWord (SHORT) - specifies the number of the word to query. Returns This function returns the length of the specified word. Notes Use CmnStrQueryWordLength to query the length of a specified word in a line of ASCII data. Related information o CmnStrQueryWord o CmnStrQueryWordCount o CmnStrQueryWordPosition ═══ 14.8. CmnStrQueryWordPosition ═══ CmnStrQueryWordPosition Purpose This function queries the position of a specified word in a line. Syntax (SHORT)CmnStrQueryWordPosition(pchLine,sWord); Parameters pchLine (PCHAR) - points to the line to query. sWord (SHORT) - specifies the number of the word to query. Returns This function returns the 0-based index of the beginning of the specified word in the line. Notes Use CmnStrQueryWordPosition to query the position of a word in a line of ASCII data. Related information o CmnStrQueryWord o CmnStrQueryWordCount o CmnStrQueryWordLength ═══ 14.9. CmnStrStripSpace ═══ CmnStrStripSpace Purpose This function strips the whitespace from the beginning and/or the end of a string. Syntax (BOOL)CmnStrStripSpace(pchString,usOptions); Parameters pchString (PCHAR) - points to the string to strip. usOptions (USHORT) - specifies the side to strip from as an SPS_ constant. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnStrStripSpace to strip the white space from a string. Related information o SPS_ constants ═══ 15. Screen I/O routines ═══ The purpose of this group is to provide miscellaneous text-mode functions. Listed below are the functions which comprise this group: o CmnVioDisplayMessage o CmnVioGetString o CmnVioLoadMessage ═══ 15.1. CmnVioDisplayMessage ═══ CmnVioDisplayMessage Purpose This function loads a message from a message file and writes it to stderr. Syntax (BOOL)CmnVioDisplayMessage(pchMsgFile,ulId,...); Parameters pchMsgFile (PCHAR) - points to the name of the message file. Even if the message file is bound to the executable, this must be the name of the original message file. ulId (ULONG) - specifies the identifier of the message to load. ... (va_list) - specifies any additional arguments referred to by the message. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnVioDisplayMessage to load and display a message from the specified message file. Note that while fprintf will allow fields whose descriptors begin with a width specifier (e.g. "%05d%cdq.), this function does not since DosGetMessage attempts to substitute positional parameters when it encounters this. ═══ 15.2. CmnVioGetString ═══ CmnVioLoadMessage Purpose This function gets a string from the user. Syntax (BOOL)CmnVioGetString(pchBuf,ulSzBuf,ulOptions); Parameters pchBuf (PCHAR) - points to the buffer to hold the result. On return, the buffer contains the string. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pchBuf. ulOptions (ULONG) - one or more VGS_* constants. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnVioGetString to get a string from the user. The advantage of using this function instead of a C library function is that this function provides the following: o Cursor movement via left, right, Ctrl-left (word-left), Ctrl-right (word-right). o Erase contents via Escape key. o Options for unreadable entry and input required. Related information o VGS_ constants ═══ 15.3. CmnVioLoadMessage ═══ CmnVioLoadMessage Purpose This function loads a message from a message file. Syntax (BOOL)CmnVioLoadMessage(pchMsgFile,ulId,pchBuf,ulSzBuf); Parameters pchMsgFile (PCHAR) - points to the name of the message file. Even if the message file is bound to the executable, this must be the name of the original message file. ulId (ULONG) - specifies the identifier of the message to load. pchBuf (PCHAR) - points to the buffer to receive the result. On return, the buffer contains the loaded message. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pchBuf. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnVioLoadMessage to load a message from the specified message file. Note that it is impossible to have a message with simply a carriage-return at the end (versus a carriage-return, line-feed pair), since the toolkit utility MKMSGF indicates this to be a syntax error. ═══ 16. Windowing routines ═══ The purpose of this group is to provide miscellaneous windowing functions. Listed below are the functions which comprise this group: o CmnWinCenterWindow o CmnWinDisplayMessage o CmnWinRestorePosition o CmnWinRestorePosFromBuffer o CmnWinSavePosition o CmnWinSavePosToBuffer ═══ 16.1. CmnWinCenterWindow ═══ CmnWinCenterWindow Purpose This function centers a window within its parent. Syntax (VOID)CmnWinCenterWindow(hwndCenter); Parameters hwndCenter (HWND) - specifies the handle of the window to center. Notes Use CmnWinCenterWindow to center a window within its parent. ═══ 16.2. CmnWinDisplayMessage ═══ CmnWinDisplayMessage Purpose This function loads a message from the STRINGTABLE and displays it in a message box. Syntax (SHORT)CmnWinDisplayMessage(hwndParent, hwndOwner, ulStyle, hmDll, usId, usHelpId, ...); Parameters hwndParent (HWND) - specifies the handle of the parent window. hwndOwner (HWND) - specifies the handle of the owner window. ulStyle (ULONG) - specifies the style of the message box. If 0 is specified, MB_INFORMATION | MB_OK is used. hmDll (HMODULE) - specifies the handle to the module containing the STRINGTABLE to load from (or NULL if the .EXE file contains the STRINGTABLE). usId (USHORT) - specifies the identifier of the message to load. usHelpId (USHORT) - specifies the identifier that is used when calling the help hook. If this is 0, no help button is shown in the message box. ... (va_list) - specifies any additional arguments referred to by the message. Returns This function returns the same result as WinMessageBox. Notes Use CmnWinDisplayMessage to load a message and display it on the screen. ═══ 16.3. CmnWinRestorePosition ═══ CmnWinRestorePosition Purpose This function restores the position of a window previously saved with CmnWinSavePosition. Syntax (BOOL)CmnWinRestorePosition(hwndWindow, hiniProfile, pchAppl, pchKey); Parameters hwndWindow (HWND) - specifies the handle of the window to restore. hiniProfile (HINI) - specifies the .INI file handle containing the saved position information. pchAppl (PCHAR) - points to the application name that the positional information was saved under. pchKey (PCHAR) - points to the key name that the positional information was saved under. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnWinRestorePosition to restore the position of a window previously saved with CmnWinSavePosition. For MDI applications, you should use the CmnWinSavePosToBuffer and CmnWinRestorePosFromBuffer function. Related information o CmnWinSavePosition ═══ 16.4. CmnWinRestorePosFromBuffer ═══ CmnWinRestorePosFromBuffer Purpose This function restores the position of a window previously saved with CmnWinSavePosToBuffer. Syntax BOOL CmnWinRestorePosFromBuffer(hwndWindow,pcpPosition); Parameters hwndWindow (HWND) - the handle of the window to restore pcpPosition (PCWPOSITION) - points to the variable containing the information to be used when restoring Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnWinRestorePosFromBuffer to restore a window's size and position from the information saved by CmnWinSavePosToBuffer. Related information o CWPOSITION data type o CmnWinSavePosToBuffer ═══ 16.5. CmnWinSavePosition ═══ CmnWinSavePosition Purpose This function saves the position of a window to be restored later with CmnWinRestorePosition. Syntax (BOOL)CmnWinSavePosition(hwndWindow, hiniProfile, pchAppl, pchKey); Parameters hwndWindow (HWND) - specifies the handle of the window to restore. hiniProfile (HINI) - specifies the .INI file handle to which the saved position information will be written. pchAppl (PCHAR) - points to the application name that the positional information will be saved under. pchKey (PCHAR) - points to the key name that the positional information will be saved under. Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnWinSavePosition to save the current size and position of the specified window for restoration at a later time. Related information o CmnWinRestorePosition ═══ 16.6. CmnWinSavePosToBuffer ═══ CmnWinSavePosToBuffer Purpose This function saves the position of a window to a buffer for later use with CmnWinRestorePosFromBuffer. Syntax BOOL CmnWinSavePosToBuffer(hwndWindow,pcpPosition); Parameters hwndWindow (HWND) - the handle of the window to restore pcpPosition (PCWPOSITION) - points to the variable to contain the information to be used when restoring Returns This function returns TRUE if successful, or FALSE otherwise. Notes Use CmnWinSavePosToBuffer to save a window's size and position so that it can be later restored using CmnWinRestorePosFromBuffer. Related information o CWPOSITION data type o CmnWinRestorePosFromBuffer ═══ ═══ Constant Meaning CCI_TYPE_CLIENT Specifies that the connection type is (to be) client. CCI_TYPE_SERVER Specifies that the connection type is (to be) server. CCI_TYPE_SERVERCONNECT Specifies that the connection type is a server data connection to a client. This can never be specified for CmnComOpenConnection. CCI_TYPE_CLIENTSERVER Specifies that the connection type is (to be) client or server. CCI_ATTR_NOACKS Specifies that no acknowledgements are to be requested by CmnComWriteData. This is useful for eliminating overhead for transaction-based protocols where the applications must implement their own acknowledgements. ═══ ═══ Constant Meaning CSC_CLOSE specifies that the connection should be closed. CSC_RESET specifies that the connection should be reset. "Reset" is an abstract term that is defined by the application. ═══ ═══ A 32-bit handle used to specify a connection. This handle is created by either CmnComOpenConnection or CmnComWaitConnection and is destroyed by CmnComCloseConnection. Related information o CmnComCloseConnection o CmnComOpenConnection o CmnComWaitConnection ═══ ═══ typedef struct _CCOPENINFO { CHAR achMachine[MAX_CONNECTNAME+1]; CHAR achConnect[MAX_CONNECTNAME+1]; USHORT usAttr; LONG lTimeout; } CCOPENINFO, FAR *PCCOPENINFO; achMachine Specifies the name of the remote machine to connect to. If this is an empty string, the connection is created locally. achConnect Specifies the name of the connection. usAttr Specifies a CCI_TYPE_* constant and zero or more CCI_ATTR_* constants. lTimeout Specifies the timeout, in seconds, for connections, data reading, and acknowledgement waiting. If this value is CCI_ATTR_NOTIMEOUT, no timeout will occur. Related information o CCI_ constants ═══ ═══ typedef struct _CCCONNECTINFO { CHAR achConnect[MAX_CONNECTNAME+1]; USHORT usAttr; ULONG ulSzData; LONG lTimeout; } CCCONNECTINFO, FAR *PCCCONNECTINFO; achConnect Specifies the fully qualified name of the connection. For clients, this will not be the name of the connection specified in the CCOPENINFO structure on the call to CmnComOpenConnection. usAttr Specifies the type of the connection and any associated attributes. These are defined as CCI_ constants. ulSzData Specifies the size, in bytes, of any data waiting to be read. This is the same value that is returned by CmnComQueryData. lTimeout Specifies the timeout value, in seconds. For calls to CmnSetHandleInfo, lTimeout is the only field that is used. All others are ignored. Related information o CCI_ constants o CmnSetHandleInfo o CmnComOpenConnection o CmnComQueryData ═══ ═══ Constant Meaning DWT_TYPE_NAME specifies that the file argument points to the file name DWT_TYPE_FILE specifies that the file argument points to a FILE structure ═══ ═══ Constant Meaning FCS_ATTR_NORMAL specifies normal files FCS_ATTR_READONLY specifies read-only files FCS_ATTR_HIDDEN specifies hidden files FCS_ATTR_SYSTEM specifies system files FCS_ATTR_DIRECTORY specifies directories FCS_ATTR_ARCHIVED specifies archived files ═══ ═══ Constant Meaning FEA_TYPE specifes the "Type" extended attribute FEA_KEYPHRASES specifes the "Key phrases" extended attribute FEA_SUBJECT specifes the "Subject" extended attribute FEA_COMMENTS specifes the "Comments" extended attribute FEA_HISTORY specifes the "History" extended attribute FEA_VERSION specifes the "Version" extended attribute FEA_ICON specifes the "Icon" extended attribute FEA_ASSOCTABLE specifes the "Assoctable" extended attribute FEA_HPFSNAME specifes the "HPFS name" extended attribute ═══ ═══ Constant Meaning FCD_OPT_WANTFORMATTED specifies that the function should fail if the destination diskette is not already formatted. If this option is not specified, and the destination diskette is not formatted, CmnFilFormatDiskette is called to format the diskette. Related information o CmnFilFormatDiskette ═══ ═══ Constant Meaning FCD_TYPE_ERROR specifies that the value of the second parameter of pfnCallback is an FCD_ERR_* constant. FCD_TYPE_MESSAGE specifies that the value of the second parameter of pfnCallback is an FCD_MSG_* constant. The return value of pfnCallback is determined by this FCD_MSG_* constant. FCD_TYPE_PROGRESS specifies that the value of the second parameter of pfnCallback is a number in the range 0-100 which specifies the percentage complete of the current operation (read, write, etc.). ═══ ═══ Constant Meaning FCD_MSG_BEGINFORMAT specifies that the format operation is beginning. FCD_MSG_BEGINREAD specifies that the read of the source diskette is beginning. FCD_MSG_BEGINVERIFY specifies that the verify of the destination diskette is beginning. FCD_MSG_BEGINWRITE specifies that the write of the destination diskette is beginning. FCD_MSG_ENDFORMAT specifies that the format operation has completed successfully. FCD_MSG_ENDREAD specifies that the source diskette was successfully read. FCD_MSG_ENDVERIFY specifies that the destination diskette was successfully verified. FCD_MSG_ENDWRITE specifies that the destination diskette was successfully written. FCD_MSG_SIZEMISMATCH specifies that the source and destination diskette sizes do not match. pfnCallback should return TRUE if a new diskette has been inserted and the operation should be retried or FALSE if the copy operation should be halted. FCD_MSG_UNFORMATTED specifies that the destination diskette is unformatted and FCD_OPT_WANTFORMATTED was specified. pfnCallback should return TRUE if a new, formatted diskette has been inserted and the operation should be retried, or FALSE if the operation is to be aborted. FCD_MSG_VALIDATESRCDISK specifies that pfnCallback should verify that the source diskette is the desired one to be copied. This is usually done by calling CmnFilQueryLabel to check the diskette label. pfnCallback should return TRUE if the correct diskette is in the drive or FALSE otherwise. Returning FALSE causes CmnFilCopyDiskette to resend the FCD_MSG_WANTSRCDISK message. FCD_MSG_WANTDESTDISK specifies that the destination diskette should be inserted in the drive. This is sent if the source and destination drives are the same and the source diskette was successfully read or if there is no diskette in the destination drive. pfnCallback should return TRUE if the diskette has been inserted and the operation should be retried or FALSE if the copy operation should be halted. FCD_MSG_WANTFORMATDISK specifies that the diskette to be formatted should be inserted in the drive. pfnCallback should return TRUE if the diskette has been inserted and the operation should be retried or FALSE if the format operation should be halted. FCD_MSG_WANTSRCDISK specifies that the source diskette should be inserted in the drive. This is sent if there is no diskette in the destination drive. pfnCallback should return TRUE if the diskette has been inserted and the operation should be retried or FALSE if the copy operation should be halted. FCD_MSG_WRITEPROTECTED specifies that the destination diskette is write-protected. pfnCallback should return TRUE if this condition has been corrected and the operation should be retried or FALSE if the copy operation should be halted. ═══ ═══ Constant Meaning FCD_ERR_ABORTED specifies that the operation was halted because pfnCallback returned FALSE for an FCD_MSG_* constant whose return value is significant. FCD_ERR_CLOSEFAILED specifies that an attempt to close the diskette failed. FCD_ERR_DESTDRVINVALID specifies that the destination drive specified does not support removable media. FCD_ERR_FORMATFAILED specifies that the format operation failed. FCD_ERR_LOCKFAILED specifies that either the source or destination drive could not be "locked". FCD_ERR_NOMEMORY specifies that there is not enough memory to hold the contents of the source diskette. FCD_ERR_OPENFAILED specifies that an attempt to open the diskette failed. FCD_ERR_READFAILED specifies that a read operation failed. FCD_ERR_SRCDRVINVALID specifies that the source drive specified does not support removable media. FCD_ERR_UNLOCKFAILED specifies that either the source or destination drive could not be "unlocked". FCD_ERR_VERIFYFAILED specifies that the verify operation failed. FCD_ERR_WRITEFAILED specifies that a write operation failed. ═══ ═══ A 32-bit handle used for file searches. It is created using the function CmnFilCreateSearch and is destroyed using the function CmnFilDestroySearch. Related information o CmnFilCreateSearch o CmnFilDestroySearch ═══ ═══ Constant Meaning CFFI_SECTOR_128B specifies 128 bytes per sector CFFI_SECTOR_256B specifies 256 bytes per sector CFFI_SECTOR_512B specifies 512 bytes per sector CFFI_SECTOR_1024B specifies 1024 bytes per sector ═══ ═══ Format parameters typedef struct _CFFORMATINFO { ULONG ulSzStruct; ULONG ulNumTracks; ULONG ulNumSectors; ULONG ulSzSector; } CFFORMATINFO, *PCFFORMATINFO; ulSzStruct specifies the size of the structure in bytes. ulNumTracks specifies the desired number of tracks. ulNumSectors specifies the number of sectors per track. ulSzSector specifies a CFFI_SECTOR_* constant describing the size of each sector. Standard formats are listed below: 360 KB (5.25 inch) ulNumTracks=40, ulNumSectors=9, ulSzSector=CFFI_SECTOR_512B 720 KB (3.5 inch) ulNumTracks=80, ulNumSectors=9, ulSzSector=CFFI_SECTOR_512B 1.2 MB (5.25 inch) ulNumTracks=80, ulNumSectors=15, ulSzSector=CFFI_SECTOR_512B 1.44 MB (3.5 inch) ulNumTracks=80, ulNumSectors=18, ulSzSector=CFFI_SECTOR_512B 2.88 MB (3.5 inch) ulNumTracks=80, ulNumSectors=36, ulSzSector=CFFI_SECTOR_512B It is recommended that your application use a standard format since unexpected results may occur otherwise (due to limitations in the file system drivers and/or hardware). Related information o CFFI_SECTOR_ constants ═══ ═══ typedef BOOL (* EXPENTRY PFNDISKIO)(ULONG,ULONG,PVOID); Input ULONG specifies an FCD_TYPE_* constant which describes how the next parameter is to be interpreted. ULONG depending on the value of the last parameter: FCD_TYPE_PROGRESS specifies a value in the range 0-100 which specifies the progress of the copy operation. FCD_TYPE_MESSAGE specifies an FCD_MSG_* constant. FCD_TYPE_ERROR specifies an FCD_ERR_* constant. PVOID specifies the user data passed to the CmnFilCopyDiskette function. For FCF_TYPE_PROGRESS, this function returns TRUE if the operation is to continue, or FALSE if the operation is to be halted. For FCD_TYPE_MESSAGE, the return value may or may not be significant, depending on the specific FCD_MSG_* constant passed. Related information o FCD_TYPE_ constants o FCD_MSG_ constants o FCD_ERR_ constants ═══ ═══ Constant Meaning LAR_TAIL specifies that the record should be inserted at the end of the list. LAR_HEAD specifies that the record should be inserted at the beginning of the list. ═══ ═══ Constant Meaning LQR_END specifies that the last record should be returned LQR_PREVIOUS specifies that the previous record should be returned LQR_NEXT specifies that the next record should be returned ═══ ═══ A 32-bit handle used to specify a linked list. It is created using the function CmnLstCreateList and is destroyed using the function CmnLstDestroyList. Related information o CmnLstCreateList o CmnLstDestroyList ═══ ═══ typedef struct _CLLISTINFO { USHORT usSzRecord; USHORT usNumRecords; PVOID pvHead; PVOID pvTail; } CLLISTINFO, FAR *PCLLISTINFO; usSzRecord Contains the size of each record in the list. usNumRecords Contains the number of records currently in the list. pvHead Points to the head of the list. pvTail Points to the tail of the list. ═══ ═══ typedef SHORT (* EXPENTRY PFNRECCOMP)(PVOID,PVOID); Input PVOID Points to the record in the list being compared PVOID Points to the application-specified data passed to the function Returns -1 If the first parameter is "less than" the second parameter 0 If the first parameter is "equal to" the second parameter 1 If the first parameter is "greater than" the second parameter ═══ ═══ typedef VOID (* EXPENTRY PFNRECFUNC)(PVOID); Input PVOID Points to a record in the list ═══ ═══ typedef BOOL (* EXPENTRY PFNRECMED)(HCLLIST,PVOID); Input HCLLIST Handle to the list to find the median of PVOID Points to a buffer large enough to hold a single record Output PVOID Points to a buffer containing the median of the specified list Returns TRUE if successful, FALSE otherwise ═══ ═══ A 32-bit handle used to specify a memory manager instance. it is created using the function CmnMemInitialize and is destroyed using the function CmnMemTerminate. Related information o CmnMemInitialize o CmnMemTerminate ═══ ═══ typedef struct _CMMEMINFO { USHORT usNumHeaps; ULONG ulSzHeap; ULONG ulMemUsed; } CMMEMINFO, FAR *PCMMEMINFO; usNumHeaps Contains the number of internal heaps to be used by the memory management routines. The default is 256. ulSzHeaps Contains the size of each heap. The default is 61440. ulMemUsed Contains the amount of memory currently allocated by this memory handle. This field is ignored by CmnMemInitialize(). ═══ ═══ A 32-bit handle used to specify an object manager instance. it is created using the function CmnObjInitialize and is destroyed using the function CmnObjTerminate. Related information o CmnObjInitialize o CmnObjTerminate ═══ ═══ typedef struct _COOBJECTINFO { HCOOBJECT hcoParent; CHAR achName[MAX_OBJECTNAME+1]; ULONG ulSzData; PVOID pvData; USHORT usNumChildren; ULONG ulReserved; } COOBJECTINFO, FAR *PCOOBJECTINFO; hcoParent Specifies the handle of the parent object. If NULL then this is the root object. achName Specifies the fully qualified name of the object. ulSzData Specifies the size of the object-data. pvData Points to the object-data. Using this field is discouraged, since this points to the object-manager's copy of the data. Instead, use the CmnObjQueryObjectData function. usNumChildren Specifies the number of immediate children. ulReserved Reserved, though it might not be zero. Related information o CmnObjQueryObjectData ═══ ═══ A 32-bit handle used to specify a set. It is created using the function CmnSetCreateSet and is destroyed using the function CmnSetDestroySet. Related information o CmnSetCreateSet o CmnSetDestroySet ═══ ═══ typedef struct _CSSETINFO { ULONG ulMaxElements; ULONG ulElementsSet; } CSSETINFO, FAR *PCSSETINFO; ulMaxElements specifies the size of the set ulElementsSet specifies the number of elements currently set in the set ═══ ═══ Constant Meaning SWS_TIMEOUT_IMMEDIATE specifies that the function should return immediately if the condition fails SWS_TIMEOUT_NEVER specifies that the function should never return until the condition is met ═══ ═══ A 32-bit handle used to specify a signal. It is created using the function CmnSigCreateSignal and is destroyed using the function CmnSigDestroySignal. Related information o CmnSigCreateSignal o CmnSigDestroySignal ═══ ═══ A 32-bit handle used to specify a signal list. It is created using the function CmnSigCreateSignalList and is destroyed using the function CmnSigDestroySignalList. Related information o CmnSigCreateSignalList o CmnSigDestroySignalList ═══ ═══ A 32-bit handle used to specify a playground instance. This is created by the CmnSprCreatePlayground function and is destroyed by the CmnSprDestroyPlayground function. Sprites must be added to a playground before they can be manipulated in any way. Related information o CmnSprAddSprite o CmnSprCreatePlayground o CmnSprDestroyPlayground o CmnSprRemoveSprite ═══ ═══ A 32-bit handle used to specify a sprite instance. This is created by the CmnSprCreateSprite function and is destroyed by the CmnSprDestroySprite function. Sprites must be added to a playground before they can be manipulated in any way. Related information o CmnSprAddSprite o CmnSprCreateSprite o CmnSprDestroySprite o CmnSprRemoveSprite ═══ ═══ Constant Meaning SCTN_TYPE_BYTE specifies that the ASCII data represents a byte of data SCTN_TYPE_SHORT specifies that the ASCII data represents a short integer (2 bytes) SCTN_TYPE_LONG specifies that the ASCII data represents a long integer (4 bytes) SCTN_TYPE_FLOAT specifies that the ASCII data represents a single-precision floating point number SCTN_TYPE_DOUBLE specifies that the ASCII data represents a double-precision floating point number The following are attribute constants which can be or'd with the above type constants. Constant Meaning SCTN_ATTR_DECIMAL specifies that the number represented in ASCII is in decimal SCTN_ATTR_HEX specifies that the number represented in ASCII is in hexadecimal ═══ ═══ Constant Meaning SPL_TYPE_BYTE specifies that the field represents a byte of data SPL_TYPE_CHAR specifies that the field represents a character of data SPL_TYPE_STRING specifies that the field represents a string of characters. Note that the length of the field does not include the terminating `\0'. SPL_TYPE_SHORT specifies that the field represents a short integer (2 bytes) SPL_TYPE_LONG specifies that the field represents a long integer (4 bytes) SPL_TYPE_FLOAT specifies that the field represents a single-precision floating point number SPL_TYPE_DOUBLE specifies that the field represents a double-precision floating point number SPL_TYPE_RESERVED specifies that the bytes in the destination buffer are to be skipped The following are attribute constants which can be or'd with the numeric type constants listed above. Constant Meaning SPL_ATTR_DECIMAL specifies that the number represented in ASCII is in decimal SPL_ATTR_HEX specifies that the number represented in ASCII is in hexadecimal Return code values are the following: Constant Meaning SPL_NOTFOUND specifies that the field was empty SPL_FOUND specifies that the field was not empty ═══ ═══ Constant Meaning SPS_LEFT Specifies that the string is to be padded on the left side. SPS_RIGHT Specifies that the string is to be padded on the right side. ═══ ═══ Command line argument descriptor typedef struct _CSCMDDESC { USHORT usId; CHAR achSwitch[SPCL_MAX_SWITCH+1]; USHORT usNumArgs; USHORT usFlags; PFNCMDARG pfnCallback; } CSCMDDESC, FAR *PCSCMDDESC; usId specifies the identifier for the command line argument achSwitch specifies the string representing the command line argument usNumArgs specifies the number of arguments the command line argument requires usFlags specifies a combination of SPCL_FLG_ constants pfnCallback points to a callback function (see below) SPCL_FLG_ constants SPCL_FLG_CASESENSITIVE specifies that achSwitch is case-sensitive SPCL_FLG_SUBSTRING specifies that achSwitch is a substring of the entire command line argument. If you specify this, you must also specify SPCL_FLG_ARGCONCAT. SPCL_FLG_ARGCONCAT specifies that the first argument is concatenated to the command line argument (e.g. "-FPa", where "a" is the first argument). PFNCMDARG function typedef BOOL (* EXPENTRY PFNCMDARG)(USHORT,PCHAR *,USHORT); Input USHORT specifies the identifier of the switch PCHAR * points to an array of arguments to the command line argument USHORT specifies the number of arguments Returns TRUE if the processing was successful, or FALSE otherwise ═══ ═══ typedef struct _CSLINEDESC { USHORT usOffset; USHORT usLength; USHORT usType; } CSLINEDESC, FAR *PCSLINEDESC; usOffset specifies the 0-based offset of the field usLength specifies the length in bytes of the field usType specifies a combination of SPL_ constants Related information o SPL_ constants ═══ ═══ typedef VOID (* EXPENTRY PFNCMDERR)(USHORT); Input USHORT Specifies the error code SPCL_ERR_NOMEMORY The function could not allocate a required amount of memory SPCL_ERR_NOTENOUGHARGS A command-line switch did not contain enough arguments SPCL_ERR_BADSWITCH An invalid switch was specified SPCL_ERR_SWITCHERROR The switch function indicated that an error occurred ═══ ═══ Constant Meaning VGS_UNREADABLE specifies that the input should not be readable. Each character is displayed as an asterisk ('*'). VGS_REQUIRED specifies that an empty string may not be returned. ═══ ═══ typedef struct _CWPOSITION { ULONG ulSzStruct; SWP swpPosition; USHORT ausExtra[6]; } CWPOSITION, FAR *PCWPOSITION; ulSzStruct specifies the size of the structure in bytes swpPosition specifies the current size and position ausExtra specifies the minimized position and the restored size and position